Skip to content

8.5. Contributions

How should you start a contribution?

Read CONTRIBUTING.md. Use an issue for a new dependency, architecture, or large curriculum change; a small reproducible fix can go directly to a focused pull request.

Bug/docs/proposal issue forms ask for the affected area, exact working directory/commands, environment, observed/expected behavior, sanitized output, learner outcome, and upstream OSS license.

Where do security or conduct reports go?

Follow SECURITY.md for vulnerabilities, unsafe defaults, supply-chain issues, or leaked credentials. Never place exploit details/secrets in a public issue. Community behavior follows CODE_OF_CONDUCT.md.

What do local hooks run?

Lefthook delegates to the same mise tasks as CI:

  • pre-commit formats dprint/Python/shell sources, restages formatter edits, runs the complete static check, then staged gitleaks/Trivy config scanning;
  • pre-push runs the offline Python test suite.

Hooks provide early feedback but do not replace reviewing the diff and running the complete gate.

What does CI run?

  • ci.yml installs dependencies, formats, checks, tests, exercises the deterministic account-free host smoke, then fails if generated edits remain.
  • scan.yml runs mise run secure: gitleaks full history plus Trivy vulnerabilities, secrets, licenses, and misconfiguration.
  • docs.yml runs the structural docs check/build on main; it deploys only when GitHub Pages is enabled, otherwise it reports that publication was skipped.

Live-model evaluations and deployments are deliberately excluded from fast deterministic CI.

What is the contributor gate?

mise run format
mise run check
mise run test
mise run scan
git status --short

Review all formatter/lock/generated changes, remove credentials/model output/runtime state, and explain any intentional remaining diff.

How should commits and pull requests be written?

Use a Conventional Commit subject (feat:, fix:, docs:, refactor:, chore:) that describes the outcome. The pull request template asks What/Why/How/Test Plan. Include screenshots only for rendered documentation/UI changes, not terminal output that may contain secrets.

The changelog is curated from user-visible outcomes rather than blindly generated from commit prefixes.

What is the contribution checkpoint?

Confirm the changed course example matches source, runs from its documented directory, states expected output and cleanup, and passes the complete gate. A green test with stale prose is not done; a rendered page with untested code is not done.